
package org.apache.mina.common;

import java.net.SocketAddress;
import java.util.Set;

/**
 * Base interface for all {@link IoAcceptor}s and {@link IoConnector}s that
 * provide I/O service and manage {@link IoSession}s.
 * 
 * 所有IoAcceptor和IoConnector的接口，提供IO服务和管理
 */
public interface IoService {
    /**
     * Adds an {@link IoServiceListener} that listens any events related with
     * this service.
     * 
     * 添加一个IoServiceListener，该监听器监听任何与该服务相关的事件。
     */
    void addListener(IoServiceListener listener);

    /**
     * Removed an existing {@link IoServiceListener} that listens any events
     * related with this service.
     * 
     * 移除IoServiceListener
     */
    void removeListener(IoServiceListener listener);

    /**
     * Returns all {@link SocketAddress}es this service is managing. If this
     * service is an {@link IoAcceptor}, a set of bind addresses will be
     * returned. If this service is an {@link IoConnector}, a set of remote
     * addresses will be returned.
     * 
     * 返回该服务目前管理的所有SocketAddress。如果该服务是一个IoAcceptor，将返回绑定的地址集合。
     * 如果该服务是IoConnector，将返回远程地址的集合。
     */
    Set<SocketAddress> getManagedServiceAddresses();

    /**
     * Returns <tt>true</tt> if this service is managing the specified
     * <tt>serviceAddress</tt>. If this service is an {@link IoAcceptor},
     * <tt>serviceAddress</tt> is a bind address. If this service is an
     * {@link IoConnector}, <tt>serviceAddress</tt> is a remote address.
     * 
     * 判断该服务是否正在管理指定的serviceAddress。 如果该服务是IoAcceptor，serviceAddress将是一个绑定的地址。
     * 如果该服务是IoConnector，serviceAddress将是一个远程地址。
     */
    boolean isManaged(SocketAddress serviceAddress);

    /**
     * Returns all sessions with the specified remote or local address, which
     * are currently managed by this service. {@link IoAcceptor} will assume the
     * specified <tt>address</tt> is a local address, and {@link IoConnector}
     * will assume it's a remote address.
     * 
     * 根据指定的远程或本地地址，返回与之相关、目前正被该服务所管理的所有session。
     * IoAcceptor将会认为传入的地址是一个本地地址，而IoConnector将认为传入的地址是远程地址。
     * 
     * @param serviceAddress
     *            the address to return all sessions for.
     * @return the sessions. An empty collection if there's no session.
     * @throws IllegalArgumentException
     *             if the specified <tt>address</tt> has not been bound.
     * @throws UnsupportedOperationException
     *             if this operation isn't supported for the particular
     *             transport type implemented by this {@link IoService}.
     * 
     * 
     */
    Set<IoSession> getManagedSessions(SocketAddress serviceAddress);

    /**
     * Returns the default configuration which is used when you didn't specify
     * any configuration.
     * 
     * 返回默认的配置，该方法用在用户并未指定任何的配置。
     */
    IoServiceConfig getDefaultConfig();

    /**
     * Returns the global {@link IoFilterChainBuilder} which will modify the
     * {@link IoFilterChain} of all {@link IoSession}s which is managed by this
     * service. The default value is an empty
     * {@link DefaultIoFilterChainBuilder}.
     * 
     * 返回全局的IoFilterChainBuilder，这个对象将会修改该服务所管理的所有的IoFilterChain及所有的IoSession。
     * 返回的默认值空的DefaultIoFilterChainBuilder。
     */
    IoFilterChainBuilder getFilterChainBuilder();

    /**
     * Sets the global {@link IoFilterChainBuilder} which will modify the
     * {@link IoFilterChain} of all {@link IoSession}s which is managed by this
     * service. If you specify <tt>null</tt> this property will be set to an
     * empty {@link DefaultIoFilterChainBuilder}.
     * 
     * 看上面的方法：getFilterChainBuilder()
     */
    void setFilterChainBuilder(IoFilterChainBuilder builder);

    /**
     * A shortcut for <tt>( ( DefaultIoFilterChainBuilder ) </tt>
     * {@link #getFilterChainBuilder()}<tt> )</tt>. Please note that the
     * returned object is not a <b>real</b> {@link IoFilterChain} but a
     * {@link DefaultIoFilterChainBuilder}. Modifying the returned builder won't
     * affect the existing {@link IoSession}s at all, because
     * {@link IoFilterChainBuilder}s affect only newly created {@link IoSession}
     * s.
     * 
     * 是getFilterChainBuilder()方法的缩写。请注意：返回的对象不是真正的IoFilterChain，
     * 而是DefaultIoFilterChainBuilder 。修改返回的builder并不会对存在的IoSession有任何的作用，因为
     * IoFilterChainBuilder 仅仅会影响到新创建的IoSession。
     * 
     * @throws IllegalStateException
     *             if the current {@link IoFilterChainBuilder} is not a
     *             {@link DefaultIoFilterChainBuilder}
     * 
     */
    DefaultIoFilterChainBuilder getFilterChain();
}
